/*
 * Copyright 2017 ~ 2025 the original author or authors. <wanglsir@gmail.com, 983708408@qq.com>
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.wl4g.component.common.remoting.standard;

import static org.apache.commons.lang3.StringUtils.isBlank;

import java.io.Serializable;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

import javax.annotation.Nullable;
import com.wl4g.component.common.collection.CollectionUtils2;
import com.wl4g.component.common.lang.Assert2;
import com.wl4g.component.common.remoting.standard.HttpMimeType.MimeTypeUtils.InvalidMimeTypeException;

/**
 * A subclass of {@link HttpMimeType} that adds support for quality parameters
 * as defined in the HTTP specification.
 *
 * @see <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1"> HTTP 1.1:
 *      Semantics and Content, section 3.1.1.1</a>
 */
public class HttpMediaType extends HttpMimeType implements Serializable {

	private static final long serialVersionUID = 2069937152339670231L;

	/**
	 * Public constant media type that includes all media ranges (i.e.
	 * "&#42;/&#42;").
	 */
	public static final HttpMediaType ALL;

	/**
	 * A String equivalent of {@link HttpMediaType#ALL}.
	 */
	public static final String ALL_VALUE = "*/*";

	/**
	 * Public constant media type for {@code application/atom+xml}.
	 */
	public static final HttpMediaType APPLICATION_ATOM_XML;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_ATOM_XML}.
	 */
	public static final String APPLICATION_ATOM_XML_VALUE = "application/atom+xml";

	/**
	 * Public constant media type for {@code application/cbor}.
	 * 
	 * @since 5.2
	 */
	public static final HttpMediaType APPLICATION_CBOR;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_CBOR}.
	 * 
	 * @since 5.2
	 */
	public static final String APPLICATION_CBOR_VALUE = "application/cbor";

	/**
	 * Public constant media type for {@code application/x-www-form-urlencoded}.
	 */
	public static final HttpMediaType APPLICATION_FORM_URLENCODED;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_FORM_URLENCODED}.
	 */
	public static final String APPLICATION_FORM_URLENCODED_VALUE = "application/x-www-form-urlencoded";

	/**
	 * Public constant media type for {@code application/json}.
	 */
	public static final HttpMediaType APPLICATION_JSON;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_JSON}.
	 * 
	 * @see #APPLICATION_JSON_UTF8_VALUE
	 */
	public static final String APPLICATION_JSON_VALUE = "application/json";

	/**
	 * Public constant media type for {@code application/json;charset=UTF-8}.
	 * 
	 * @deprecated as of 5.2 in favor of {@link #APPLICATION_JSON} since major
	 *             browsers like Chrome <a href=
	 *             "https://bugs.chromium.org/p/chromium/issues/detail?id=438464">
	 *             now comply with the specification</a> and interpret correctly
	 *             UTF-8 special characters without requiring a
	 *             {@code charset=UTF-8} parameter.
	 */
	@Deprecated
	public static final HttpMediaType APPLICATION_JSON_UTF8;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_JSON_UTF8}.
	 * 
	 * @deprecated as of 5.2 in favor of {@link #APPLICATION_JSON_VALUE} since
	 *             major browsers like Chrome <a href=
	 *             "https://bugs.chromium.org/p/chromium/issues/detail?id=438464">
	 *             now comply with the specification</a> and interpret correctly
	 *             UTF-8 special characters without requiring a
	 *             {@code charset=UTF-8} parameter.
	 */
	@Deprecated
	public static final String APPLICATION_JSON_UTF8_VALUE = "application/json;charset=UTF-8";

	/**
	 * Public constant media type for {@code application/octet-stream}.
	 */
	public static final HttpMediaType APPLICATION_OCTET_STREAM;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_OCTET_STREAM}.
	 */
	public static final String APPLICATION_OCTET_STREAM_VALUE = "application/octet-stream";

	/**
	 * Public constant media type for {@code application/pdf}.
	 * 
	 * @since 4.3
	 */
	public static final HttpMediaType APPLICATION_PDF;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_PDF}.
	 * 
	 * @since 4.3
	 */
	public static final String APPLICATION_PDF_VALUE = "application/pdf";

	/**
	 * Public constant media type for {@code application/problem+json}.
	 * 
	 * @since 5.0
	 * @see <a href="https://tools.ietf.org/html/rfc7807#section-6.1"> Problem
	 *      Details for HTTP APIs, 6.1. application/problem+json</a>
	 */
	public static final HttpMediaType APPLICATION_PROBLEM_JSON;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_PROBLEM_JSON}.
	 * 
	 * @since 5.0
	 */
	public static final String APPLICATION_PROBLEM_JSON_VALUE = "application/problem+json";

	/**
	 * Public constant media type for {@code application/problem+json}.
	 * 
	 * @since 5.0
	 * @see <a href="https://tools.ietf.org/html/rfc7807#section-6.1"> Problem
	 *      Details for HTTP APIs, 6.1. application/problem+json</a>
	 * @deprecated as of 5.2 in favor of {@link #APPLICATION_PROBLEM_JSON} since
	 *             major browsers like Chrome <a href=
	 *             "https://bugs.chromium.org/p/chromium/issues/detail?id=438464">
	 *             now comply with the specification</a> and interpret correctly
	 *             UTF-8 special characters without requiring a
	 *             {@code charset=UTF-8} parameter.
	 */
	@Deprecated
	public static final HttpMediaType APPLICATION_PROBLEM_JSON_UTF8;

	/**
	 * A String equivalent of
	 * {@link HttpMediaType#APPLICATION_PROBLEM_JSON_UTF8}.
	 * 
	 * @since 5.0
	 * @deprecated as of 5.2 in favor of {@link #APPLICATION_PROBLEM_JSON_VALUE}
	 *             since major browsers like Chrome <a href=
	 *             "https://bugs.chromium.org/p/chromium/issues/detail?id=438464">
	 *             now comply with the specification</a> and interpret correctly
	 *             UTF-8 special characters without requiring a
	 *             {@code charset=UTF-8} parameter.
	 */
	@Deprecated
	public static final String APPLICATION_PROBLEM_JSON_UTF8_VALUE = "application/problem+json;charset=UTF-8";

	/**
	 * Public constant media type for {@code application/problem+xml}.
	 * 
	 * @since 5.0
	 * @see <a href="https://tools.ietf.org/html/rfc7807#section-6.2"> Problem
	 *      Details for HTTP APIs, 6.2. application/problem+xml</a>
	 */
	public static final HttpMediaType APPLICATION_PROBLEM_XML;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_PROBLEM_XML}.
	 * 
	 * @since 5.0
	 */
	public static final String APPLICATION_PROBLEM_XML_VALUE = "application/problem+xml";

	/**
	 * Public constant media type for {@code application/rss+xml}.
	 * 
	 * @since 4.3.6
	 */
	public static final HttpMediaType APPLICATION_RSS_XML;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_RSS_XML}.
	 * 
	 * @since 4.3.6
	 */
	public static final String APPLICATION_RSS_XML_VALUE = "application/rss+xml";

	/**
	 * Public constant media type for {@code application/stream+json}.
	 * 
	 * @since 5.0
	 */
	public static final HttpMediaType APPLICATION_STREAM_JSON;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_STREAM_JSON}.
	 * 
	 * @since 5.0
	 */
	public static final String APPLICATION_STREAM_JSON_VALUE = "application/stream+json";

	/**
	 * Public constant media type for {@code application/xhtml+xml}.
	 */
	public static final HttpMediaType APPLICATION_XHTML_XML;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_XHTML_XML}.
	 */
	public static final String APPLICATION_XHTML_XML_VALUE = "application/xhtml+xml";

	/**
	 * Public constant media type for {@code application/xml}.
	 */
	public static final HttpMediaType APPLICATION_XML;

	/**
	 * A String equivalent of {@link HttpMediaType#APPLICATION_XML}.
	 */
	public static final String APPLICATION_XML_VALUE = "application/xml";

	/**
	 * Public constant media type for {@code image/gif}.
	 */
	public static final HttpMediaType IMAGE_GIF;

	/**
	 * A String equivalent of {@link HttpMediaType#IMAGE_GIF}.
	 */
	public static final String IMAGE_GIF_VALUE = "image/gif";

	/**
	 * Public constant media type for {@code image/jpeg}.
	 */
	public static final HttpMediaType IMAGE_JPEG;

	/**
	 * A String equivalent of {@link HttpMediaType#IMAGE_JPEG}.
	 */
	public static final String IMAGE_JPEG_VALUE = "image/jpeg";

	/**
	 * Public constant media type for {@code image/png}.
	 */
	public static final HttpMediaType IMAGE_PNG;

	/**
	 * A String equivalent of {@link HttpMediaType#IMAGE_PNG}.
	 */
	public static final String IMAGE_PNG_VALUE = "image/png";

	/**
	 * Public constant media type for {@code multipart/form-data}.
	 */
	public static final HttpMediaType MULTIPART_FORM_DATA;

	/**
	 * A String equivalent of {@link HttpMediaType#MULTIPART_FORM_DATA}.
	 */
	public static final String MULTIPART_FORM_DATA_VALUE = "multipart/form-data";

	/**
	 * Public constant media type for {@code multipart/mixed}.
	 * 
	 * @since 5.2
	 */
	public static final HttpMediaType MULTIPART_MIXED;

	/**
	 * A String equivalent of {@link HttpMediaType#MULTIPART_MIXED}.
	 * 
	 * @since 5.2
	 */
	public static final String MULTIPART_MIXED_VALUE = "multipart/mixed";

	/**
	 * Public constant media type for {@code text/event-stream}.
	 * 
	 * @since 4.3.6
	 * @see <a href="https://www.w3.org/TR/eventsource/">Server-Sent Events W3C
	 *      recommendation</a>
	 */
	public static final HttpMediaType TEXT_EVENT_STREAM;

	/**
	 * A String equivalent of {@link HttpMediaType#TEXT_EVENT_STREAM}.
	 * 
	 * @since 4.3.6
	 */
	public static final String TEXT_EVENT_STREAM_VALUE = "text/event-stream";

	/**
	 * Public constant media type for {@code text/html}.
	 */
	public static final HttpMediaType TEXT_HTML;

	/**
	 * A String equivalent of {@link HttpMediaType#TEXT_HTML}.
	 */
	public static final String TEXT_HTML_VALUE = "text/html";

	/**
	 * Public constant media type for {@code text/markdown}.
	 * 
	 * @since 4.3
	 */
	public static final HttpMediaType TEXT_MARKDOWN;

	/**
	 * A String equivalent of {@link HttpMediaType#TEXT_MARKDOWN}.
	 * 
	 * @since 4.3
	 */
	public static final String TEXT_MARKDOWN_VALUE = "text/markdown";

	/**
	 * Public constant media type for {@code text/plain}.
	 */
	public static final HttpMediaType TEXT_PLAIN;

	/**
	 * A String equivalent of {@link HttpMediaType#TEXT_PLAIN}.
	 */
	public static final String TEXT_PLAIN_VALUE = "text/plain";

	/**
	 * Public constant media type for {@code text/xml}.
	 */
	public static final HttpMediaType TEXT_XML;

	/**
	 * A String equivalent of {@link HttpMediaType#TEXT_XML}.
	 */
	public static final String TEXT_XML_VALUE = "text/xml";

	private static final String PARAM_QUALITY_FACTOR = "q";

	static {
		// Not using "valueOf' to avoid static init cost
		ALL = new HttpMediaType("*", "*");
		APPLICATION_ATOM_XML = new HttpMediaType("application", "atom+xml");
		APPLICATION_CBOR = new HttpMediaType("application", "cbor");
		APPLICATION_FORM_URLENCODED = new HttpMediaType("application", "x-www-form-urlencoded");
		APPLICATION_JSON = new HttpMediaType("application", "json");
		APPLICATION_JSON_UTF8 = new HttpMediaType("application", "json", StandardCharsets.UTF_8);
		APPLICATION_OCTET_STREAM = new HttpMediaType("application", "octet-stream");
		APPLICATION_PDF = new HttpMediaType("application", "pdf");
		APPLICATION_PROBLEM_JSON = new HttpMediaType("application", "problem+json");
		APPLICATION_PROBLEM_JSON_UTF8 = new HttpMediaType("application", "problem+json", StandardCharsets.UTF_8);
		APPLICATION_PROBLEM_XML = new HttpMediaType("application", "problem+xml");
		APPLICATION_RSS_XML = new HttpMediaType("application", "rss+xml");
		APPLICATION_STREAM_JSON = new HttpMediaType("application", "stream+json");
		APPLICATION_XHTML_XML = new HttpMediaType("application", "xhtml+xml");
		APPLICATION_XML = new HttpMediaType("application", "xml");
		IMAGE_GIF = new HttpMediaType("image", "gif");
		IMAGE_JPEG = new HttpMediaType("image", "jpeg");
		IMAGE_PNG = new HttpMediaType("image", "png");
		MULTIPART_FORM_DATA = new HttpMediaType("multipart", "form-data");
		MULTIPART_MIXED = new HttpMediaType("multipart", "mixed");
		TEXT_EVENT_STREAM = new HttpMediaType("text", "event-stream");
		TEXT_HTML = new HttpMediaType("text", "html");
		TEXT_MARKDOWN = new HttpMediaType("text", "markdown");
		TEXT_PLAIN = new HttpMediaType("text", "plain");
		TEXT_XML = new HttpMediaType("text", "xml");
	}

	/**
	 * Create a new {@code MediaType} for the given primary type.
	 * <p>
	 * The {@linkplain #getSubtype() subtype} is set to "&#42;", parameters
	 * empty.
	 * 
	 * @param type
	 *            the primary type
	 * @throws IllegalArgumentException
	 *             if any of the parameters contain illegal characters
	 */
	public HttpMediaType(String type) {
		super(type);
	}

	/**
	 * Create a new {@code MediaType} for the given primary type and subtype.
	 * <p>
	 * The parameters are empty.
	 * 
	 * @param type
	 *            the primary type
	 * @param subtype
	 *            the subtype
	 * @throws IllegalArgumentException
	 *             if any of the parameters contain illegal characters
	 */
	public HttpMediaType(String type, String subtype) {
		super(type, subtype, Collections.emptyMap());
	}

	/**
	 * Create a new {@code MediaType} for the given type, subtype, and character
	 * set.
	 * 
	 * @param type
	 *            the primary type
	 * @param subtype
	 *            the subtype
	 * @param charset
	 *            the character set
	 * @throws IllegalArgumentException
	 *             if any of the parameters contain illegal characters
	 */
	public HttpMediaType(String type, String subtype, Charset charset) {
		super(type, subtype, charset);
	}

	/**
	 * Create a new {@code MediaType} for the given type, subtype, and quality
	 * value.
	 * 
	 * @param type
	 *            the primary type
	 * @param subtype
	 *            the subtype
	 * @param qualityValue
	 *            the quality value
	 * @throws IllegalArgumentException
	 *             if any of the parameters contain illegal characters
	 */
	public HttpMediaType(String type, String subtype, double qualityValue) {
		this(type, subtype, Collections.singletonMap(PARAM_QUALITY_FACTOR, Double.toString(qualityValue)));
	}

	/**
	 * Copy-constructor that copies the type, subtype and parameters of the
	 * given {@code MediaType}, and allows to set the specified character set.
	 * 
	 * @param other
	 *            the other media type
	 * @param charset
	 *            the character set
	 * @throws IllegalArgumentException
	 *             if any of the parameters contain illegal characters
	 * @since 4.3
	 */
	public HttpMediaType(HttpMediaType other, Charset charset) {
		super(other, charset);
	}

	/**
	 * Copy-constructor that copies the type and subtype of the given
	 * {@code MediaType}, and allows for different parameters.
	 * 
	 * @param other
	 *            the other media type
	 * @param parameters
	 *            the parameters, may be {@code null}
	 * @throws IllegalArgumentException
	 *             if any of the parameters contain illegal characters
	 */
	public HttpMediaType(HttpMediaType other, @Nullable Map<String, String> parameters) {
		super(other.getType(), other.getSubtype(), parameters);
	}

	/**
	 * Create a new {@code MediaType} for the given type, subtype, and
	 * parameters.
	 * 
	 * @param type
	 *            the primary type
	 * @param subtype
	 *            the subtype
	 * @param parameters
	 *            the parameters, may be {@code null}
	 * @throws IllegalArgumentException
	 *             if any of the parameters contain illegal characters
	 */
	public HttpMediaType(String type, String subtype, @Nullable Map<String, String> parameters) {
		super(type, subtype, parameters);
	}

	@Override
	protected void checkParameters(String attribute, String value) {
		super.checkParameters(attribute, value);
		if (PARAM_QUALITY_FACTOR.equals(attribute)) {
			value = unquote(value);
			double d = Double.parseDouble(value);
			Assert2.isTrue(d >= 0D && d <= 1D, "Invalid quality value \"" + value + "\": should be between 0.0 and 1.0");
		}
	}

	/**
	 * Return the quality factor, as indicated by a {@code q} parameter, if any.
	 * Defaults to {@code 1.0}.
	 * 
	 * @return the quality factor as double value
	 */
	public double getQualityValue() {
		String qualityFactor = getParameter(PARAM_QUALITY_FACTOR);
		return (qualityFactor != null ? Double.parseDouble(unquote(qualityFactor)) : 1D);
	}

	/**
	 * Indicate whether this {@code MediaType} includes the given media type.
	 * <p>
	 * For instance, {@code text/*} includes {@code text/plain} and
	 * {@code text/html}, and {@code application/*+xml} includes
	 * {@code application/soap+xml}, etc. This method is <b>not</b> symmetric.
	 * <p>
	 * Simply calls {@link HttpMimeType#includes(HttpMimeType)} but declared
	 * with a {@code MediaType} parameter for binary backwards compatibility.
	 * 
	 * @param other
	 *            the reference media type with which to compare
	 * @return {@code true} if this media type includes the given media type;
	 *         {@code false} otherwise
	 */
	public boolean includes(@Nullable HttpMediaType other) {
		return super.includes(other);
	}

	/**
	 * Indicate whether this {@code MediaType} is compatible with the given
	 * media type.
	 * <p>
	 * For instance, {@code text/*} is compatible with {@code text/plain},
	 * {@code text/html}, and vice versa. In effect, this method is similar to
	 * {@link #includes}, except that it <b>is</b> symmetric.
	 * <p>
	 * Simply calls {@link HttpMimeType#isCompatibleWith(HttpMimeType)} but
	 * declared with a {@code MediaType} parameter for binary backwards
	 * compatibility.
	 * 
	 * @param other
	 *            the reference media type with which to compare
	 * @return {@code true} if this media type is compatible with the given
	 *         media type; {@code false} otherwise
	 */
	public boolean isCompatibleWith(@Nullable HttpMediaType other) {
		return super.isCompatibleWith(other);
	}

	/**
	 * Return a replica of this instance with the quality value of the given
	 * {@code MediaType}.
	 * 
	 * @return the same instance if the given MediaType doesn't have a quality
	 *         value, or a new one otherwise
	 */
	public HttpMediaType copyQualityValue(HttpMediaType mediaType) {
		if (!mediaType.getParameters().containsKey(PARAM_QUALITY_FACTOR)) {
			return this;
		}
		Map<String, String> params = new LinkedHashMap<>(getParameters());
		params.put(PARAM_QUALITY_FACTOR, mediaType.getParameters().get(PARAM_QUALITY_FACTOR));
		return new HttpMediaType(this, params);
	}

	/**
	 * Return a replica of this instance with its quality value removed.
	 * 
	 * @return the same instance if the media type doesn't contain a quality
	 *         value, or a new one otherwise
	 */
	public HttpMediaType removeQualityValue() {
		if (!getParameters().containsKey(PARAM_QUALITY_FACTOR)) {
			return this;
		}
		Map<String, String> params = new LinkedHashMap<>(getParameters());
		params.remove(PARAM_QUALITY_FACTOR);
		return new HttpMediaType(this, params);
	}

	/**
	 * Parse the given String value into a {@code MediaType} object.
	 * 
	 * @param value
	 *            the string to parse
	 * @throws InvalidMediaTypeException
	 *             if the media type value cannot be parsed
	 * @see #parseMediaType(String)
	 */
	public static HttpMediaType valueOf(String value) {
		return parseMediaType(value);
	}

	/**
	 * Parse the given String into a single {@code MediaType}.
	 * 
	 * @param mediaType
	 *            the string to parse
	 * @return the media type
	 * @throws InvalidMediaTypeException
	 *             if the media type value cannot be parsed
	 */
	public static HttpMediaType parseMediaType(String mediaType) {
		HttpMimeType type;
		try {
			type = MimeTypeUtils.parseMimeType(mediaType);
		} catch (InvalidMimeTypeException ex) {
			throw new InvalidMediaTypeException(ex);
		}
		try {
			return new HttpMediaType(type.getType(), type.getSubtype(), type.getParameters());
		} catch (IllegalArgumentException ex) {
			throw new InvalidMediaTypeException(mediaType, ex.getMessage());
		}
	}

	/**
	 * Parse the comma-separated string into a list of {@code MediaType}
	 * objects.
	 * <p>
	 * This method can be used to parse an Accept or Content-Type header.
	 * 
	 * @param mediaTypes
	 *            the string to parse
	 * @return the list of media types
	 * @throws InvalidMediaTypeException
	 *             if the media type value cannot be parsed
	 */
	public static List<HttpMediaType> parseMediaTypes(@Nullable String mediaTypes) {
		if (isBlank(mediaTypes)) {
			return Collections.emptyList();
		}
		// Avoid using java.util.stream.Stream in hot paths
		List<String> tokenizedTypes = MimeTypeUtils.tokenize(mediaTypes);
		List<HttpMediaType> result = new ArrayList<>(tokenizedTypes.size());
		for (String type : tokenizedTypes) {
			if (!isBlank(type)) {
				result.add(parseMediaType(type));
			}
		}
		return result;
	}

	/**
	 * Parse the given list of (potentially) comma-separated strings into a list
	 * of {@code MediaType} objects.
	 * <p>
	 * This method can be used to parse an Accept or Content-Type header.
	 * 
	 * @param mediaTypes
	 *            the string to parse
	 * @return the list of media types
	 * @throws InvalidMediaTypeException
	 *             if the media type value cannot be parsed
	 * @since 4.3.2
	 */
	public static List<HttpMediaType> parseMediaTypes(@Nullable List<String> mediaTypes) {
		if (CollectionUtils2.isEmpty(mediaTypes)) {
			return Collections.emptyList();
		} else if (mediaTypes.size() == 1) {
			return parseMediaTypes(mediaTypes.get(0));
		} else {
			List<HttpMediaType> result = new ArrayList<>(8);
			for (String mediaType : mediaTypes) {
				result.addAll(parseMediaTypes(mediaType));
			}
			return result;
		}
	}

	/**
	 * Re-create the given mime types as media types.
	 * 
	 * @since 5.0
	 */
	public static List<HttpMediaType> asMediaTypes(List<HttpMimeType> mimeTypes) {
		List<HttpMediaType> mediaTypes = new ArrayList<>(mimeTypes.size());
		for (HttpMimeType mimeType : mimeTypes) {
			mediaTypes.add(HttpMediaType.asMediaType(mimeType));
		}
		return mediaTypes;
	}

	/**
	 * Re-create the given mime type as a media type.
	 * 
	 * @since 5.0
	 */
	public static HttpMediaType asMediaType(HttpMimeType mimeType) {
		if (mimeType instanceof HttpMediaType) {
			return (HttpMediaType) mimeType;
		}
		return new HttpMediaType(mimeType.getType(), mimeType.getSubtype(), mimeType.getParameters());
	}

	/**
	 * Return a string representation of the given list of {@code MediaType}
	 * objects.
	 * <p>
	 * This method can be used to for an {@code Accept} or {@code Content-Type}
	 * header.
	 * 
	 * @param mediaTypes
	 *            the media types to create a string representation for
	 * @return the string representation
	 */
	public static String toString(Collection<HttpMediaType> mediaTypes) {
		return MimeTypeUtils.toString(mediaTypes);
	}

	/**
	 * Sorts the given list of {@code MediaType} objects by specificity.
	 * <p>
	 * Given two media types:
	 * <ol>
	 * <li>if either media type has a {@linkplain #isWildcardType() wildcard
	 * type}, then the media type without the wildcard is ordered before the
	 * other.</li>
	 * <li>if the two media types have different {@linkplain #getType() types},
	 * then they are considered equal and remain their current order.</li>
	 * <li>if either media type has a {@linkplain #isWildcardSubtype() wildcard
	 * subtype}, then the media type without the wildcard is sorted before the
	 * other.</li>
	 * <li>if the two media types have different {@linkplain #getSubtype()
	 * subtypes}, then they are considered equal and remain their current
	 * order.</li>
	 * <li>if the two media types have different {@linkplain #getQualityValue()
	 * quality value}, then the media type with the highest quality value is
	 * ordered before the other.</li>
	 * <li>if the two media types have a different amount of
	 * {@linkplain #getParameter(String) parameters}, then the media type with
	 * the most parameters is ordered before the other.</li>
	 * </ol>
	 * <p>
	 * For example: <blockquote>audio/basic &lt; audio/* &lt;
	 * *&#047;*</blockquote> <blockquote>audio/* &lt; audio/*;q=0.7;
	 * audio/*;q=0.3</blockquote> <blockquote>audio/basic;level=1 &lt;
	 * audio/basic</blockquote> <blockquote>audio/basic ==
	 * text/html</blockquote> <blockquote>audio/basic == audio/wave</blockquote>
	 * 
	 * @param mediaTypes
	 *            the list of media types to be sorted
	 * @see <a href="https://tools.ietf.org/html/rfc7231#section-5.3.2">HTTP
	 *      1.1: Semantics and Content, section 5.3.2</a>
	 */
	public static void sortBySpecificity(List<HttpMediaType> mediaTypes) {
		Assert2.notNull(mediaTypes, "'mediaTypes' must not be null");
		if (mediaTypes.size() > 1) {
			mediaTypes.sort(SPECIFICITY_COMPARATOR);
		}
	}

	/**
	 * Sorts the given list of {@code MediaType} objects by quality value.
	 * <p>
	 * Given two media types:
	 * <ol>
	 * <li>if the two media types have different {@linkplain #getQualityValue()
	 * quality value}, then the media type with the highest quality value is
	 * ordered before the other.</li>
	 * <li>if either media type has a {@linkplain #isWildcardType() wildcard
	 * type}, then the media type without the wildcard is ordered before the
	 * other.</li>
	 * <li>if the two media types have different {@linkplain #getType() types},
	 * then they are considered equal and remain their current order.</li>
	 * <li>if either media type has a {@linkplain #isWildcardSubtype() wildcard
	 * subtype}, then the media type without the wildcard is sorted before the
	 * other.</li>
	 * <li>if the two media types have different {@linkplain #getSubtype()
	 * subtypes}, then they are considered equal and remain their current
	 * order.</li>
	 * <li>if the two media types have a different amount of
	 * {@linkplain #getParameter(String) parameters}, then the media type with
	 * the most parameters is ordered before the other.</li>
	 * </ol>
	 * 
	 * @param mediaTypes
	 *            the list of media types to be sorted
	 * @see #getQualityValue()
	 */
	public static void sortByQualityValue(List<HttpMediaType> mediaTypes) {
		Assert2.notNull(mediaTypes, "'mediaTypes' must not be null");
		if (mediaTypes.size() > 1) {
			mediaTypes.sort(QUALITY_VALUE_COMPARATOR);
		}
	}

	/**
	 * Sorts the given list of {@code MediaType} objects by specificity as the
	 * primary criteria and quality value the secondary.
	 * 
	 * @see HttpMediaType#sortBySpecificity(List)
	 * @see HttpMediaType#sortByQualityValue(List)
	 */
	public static void sortBySpecificityAndQuality(List<HttpMediaType> mediaTypes) {
		Assert2.notNull(mediaTypes, "'mediaTypes' must not be null");
		if (mediaTypes.size() > 1) {
			mediaTypes.sort(HttpMediaType.SPECIFICITY_COMPARATOR.thenComparing(HttpMediaType.QUALITY_VALUE_COMPARATOR));
		}
	}

	/**
	 * Comparator used by {@link #sortByQualityValue(List)}.
	 */
	public static final Comparator<HttpMediaType> QUALITY_VALUE_COMPARATOR = (mediaType1, mediaType2) -> {
		double quality1 = mediaType1.getQualityValue();
		double quality2 = mediaType2.getQualityValue();
		int qualityComparison = Double.compare(quality2, quality1);
		if (qualityComparison != 0) {
			return qualityComparison; // audio/*;q=0.7 < audio/*;q=0.3
		} else if (mediaType1.isWildcardType() && !mediaType2.isWildcardType()) { // */*
																					// <
																					// audio/*
			return 1;
		} else if (mediaType2.isWildcardType() && !mediaType1.isWildcardType()) { // audio/*
																					// >
																					// */*
			return -1;
		} else if (!mediaType1.getType().equals(mediaType2.getType())) { // audio/basic
																			// ==
																			// text/html
			return 0;
		} else { // mediaType1.getType().equals(mediaType2.getType())
			if (mediaType1.isWildcardSubtype() && !mediaType2.isWildcardSubtype()) { // audio/*
																						// <
																						// audio/basic
				return 1;
			} else if (mediaType2.isWildcardSubtype() && !mediaType1.isWildcardSubtype()) { // audio/basic
																							// >
																							// audio/*
				return -1;
			} else if (!mediaType1.getSubtype().equals(mediaType2.getSubtype())) { // audio/basic
																					// ==
																					// audio/wave
				return 0;
			} else {
				int paramsSize1 = mediaType1.getParameters().size();
				int paramsSize2 = mediaType2.getParameters().size();
				return Integer.compare(paramsSize2, paramsSize1); // audio/basic;level=1
																	// <
																	// audio/basic
			}
		}
	};

	/**
	 * Comparator used by {@link #sortBySpecificity(List)}.
	 */
	public static final Comparator<HttpMediaType> SPECIFICITY_COMPARATOR = new SpecificityComparator<HttpMediaType>() {

		@Override
		protected int compareParameters(HttpMediaType mediaType1, HttpMediaType mediaType2) {
			double quality1 = mediaType1.getQualityValue();
			double quality2 = mediaType2.getQualityValue();
			int qualityComparison = Double.compare(quality2, quality1);
			if (qualityComparison != 0) {
				return qualityComparison; // audio/*;q=0.7 < audio/*;q=0.3
			}
			return super.compareParameters(mediaType1, mediaType2);
		}
	};

	/**
	 * Exception thrown from {@link HttpMediaType#parseMediaType(String)} in
	 * case of encountering an invalid media type specification String.
	 *
	 * @author Juergen Hoeller
	 * @since 3.2.2
	 */
	@SuppressWarnings("serial")
	public static class InvalidMediaTypeException extends IllegalArgumentException {

		private String mediaType;

		/**
		 * Create a new InvalidMediaTypeException for the given media type.
		 * 
		 * @param mediaType
		 *            the offending media type
		 * @param message
		 *            a detail message indicating the invalid part
		 */
		public InvalidMediaTypeException(String mediaType, String message) {
			super("Invalid media type \"" + mediaType + "\": " + message);
			this.mediaType = mediaType;
		}

		/**
		 * Constructor that allows wrapping {@link InvalidMimeTypeException}.
		 */
		InvalidMediaTypeException(InvalidMimeTypeException ex) {
			super(ex.getMessage(), ex);
			this.mediaType = ex.getMimeType();
		}

		/**
		 * Return the offending media type.
		 */
		public String getMediaType() {
			return this.mediaType;
		}

	}

}